Contents

The epivizrChart package is an R interface to the Epiviz component library. This allows users to create interactive charts to visualize and explore bioconductor data objects in RMarkdown and shiny applications. Epiviz Web components are built using the Google Polymer library. This vignette demonstrates the use of the visualization components in RMarkdown documents.

Sample data sets we will be using for the vignette.

data(tcga_colon_blocks)
data(tcga_colon_curves)
data(tcga_colon_expression)
data(apColonData)

1 Visualizing Bioconductor data types

epivizrChart supports various bioconductor data types for ex: Genomic Ranges, ExpressionSet, SummarizedExperiment etc. The package automatically infers a chart type to visualize the data from these objects.

For example, to visualize hg19 reference genome as a genes track at a particular genomic location (chr, start, end)

library(Homo.sapiens)

genes_track <- epivizChart(Homo.sapiens, chr="chr11", start=118000000, end=121000000)
## creating gene annotation (it may take a bit)
##   403 genes were dropped because they have exons located on both strands
##   of the same reference sequence or on more than one reference sequence,
##   so cannot be represented by a single genomic range.
##   Use 'single.strand.genes.only=FALSE' to get all the genes in a
##   GRangesList object, or use suppressMessages() to suppress this message.
## 'select()' returned 1:1 mapping between keys and columns
genes_track

Users also have an option to use a specific chart type using the the chart parameter. A complete list of supported visualizations is available on the Epiviz Component Library

scatter_plot <- epivizChart(tcga_colon_curves, chr="chr11", start=99800000, end=103383180, type="bp", columns=c("cancerMean","normalMean"), chart="ScatterPlot")
scatter_plot

2 Compose custom genome viewers

In addition to visualizing data, epivizrChart allows users to quickly compose custom genome viewers for their data This allows users to incorporate interactive data exploration in their analysis workflows. We provide a couple of ways to compose custom genome viewers and various interactions between these components.

2.1 Visualizing data across the entire Genome (Epiviz Environment)

To enable this, we built the epiviz-environment that visualizes data across the entire genome. An example use case would be to explore gene expression patterns across conditions (tumour vs normal etc) or tissue types. To visualize data genome wide -

epivizEnv <- epivizEnv()

blocks_track <- epivizEnv$plot(tcga_colon_curves, type="bp", columns=c("cancerMean","normalMean"), chart="ScatterPlot")

epivizEnv

2.2 Visualize data for a specific genomic location (Epiviz Navigation)

epiviz-navigation extends the environment element with genomic context linked to it. This allows users to navigate to a specific gene or genomic region of interest. Navigational controls are disabled in RMarkdown documents since there is no active server running to respond to interface requests but are enabled in interactive sessions and shiny applications.

To create a navigation at a specific genomic location (chr, start and end),

epivizNav <- epivizNav(chr="chr11", start=118000000, end=121000000)

genes_track <- epivizNav$plot(Homo.sapiens)
## creating gene annotation (it may take a bit)
##   403 genes were dropped because they have exons located on both strands
##   of the same reference sequence or on more than one reference sequence,
##   so cannot be represented by a single genomic range.
##   Use 'single.strand.genes.only=FALSE' to get all the genes in a
##   GRangesList object, or use suppressMessages() to suppress this message.
## 'select()' returned 1:1 mapping between keys and columns
blocks_track <- epivizNav$plot(tcga_colon_blocks, datasource_name="450kMeth")

epivizNav

3 Using Interactive Mode

So far, we’ve seen how to add charts and static viewers. This section explores interactive viewers using epivizrChart. The interactive mode takes advantage of the websocket protocol to create an active connection between the R-session and the epiviz components. In interactive mode, data is not embedded along with the components, So the charts make data requests to the R-session through the websocket connection to get data.

To use charts in interactive mode, first we create an epiviz environment with interactive mode enabled.

library(epivizrChart)

# initialize environment
epivizEnv <- epivizNav(chr="chr11", start=118000000, end=121000000, interactive=TRUE)

We then create an instance of an epivizrServer to manage websocket connections. The register_all_the_epiviz_things adds listeners and handlers to manage data requests.

library(epivizrServer)

library(Homo.sapiens)
data(tcga_colon_blocks)

# initialize server
server <- epivizrServer::createServer()

# register all our actions between websocket and components
epivizrChart:::.register_all_the_epiviz_things(server, epivizEnv)

# start server
server$start_server()

We now have an epiviz environment and an active websocket connection to the R-session. Adding and managing charts is exactly the same as described earlier.

# plot charts
blocks_track <- epivizEnv$plot(tcga_colon_blocks, datasource_name="450kMeth")
epivizEnv

genes <- epivizEnv$plot(Homo.sapiens)
epivizEnv

Finally close the server

server$stop_server()